# Multi-Level Marketing (MLM) Business Rules

This document contains the business rules and parameters for the MLM system, including investment tiers, commission structures, and deposit/withdrawal rules. This information is primarily for business owners and stakeholders.

**Related Documents:**
- **Requirements Analysis:** See `/docs/requirements-analysis.md` for complete system requirements and technical specifications
- **Backend Architecture:** See `/docs/backend-architecture.md` for Django implementation details
- **Frontend Architecture:** See `/docs/frontend-architecture.md` for React frontend implementation details

---

## Investment Tiers

Investment tiers determine the daily reward percentage and contract duration based on the investment amount.

| Tier | Investment Amount Range | Daily Reward Rate | Contract Duration (Days) |
|------|------------------------|-------------------|--------------------------|
| Tier 1 | ≤ $100 (less than or equal to $100) | 1.0% | 120 |
| Tier 2 | ≤ $500 (less than or equal to $500) | 1.5% | 130 |
| Tier 3 | ≤ $1,000 (less than or equal to $1,000) | 2.0% | 140 |
| Tier 4 | ≤ $2,000 (less than or equal to $2,000) | 2.5% | 150 |
| Tier 5 | ≤ $5,000 (less than or equal to $5,000) | 3.0% | 160 |
| Tier 6 | > $5,000 (greater than $5,000) | 3.5% | 180 |

### Investment Rules

| Rule | Value |
|------|-------|
| Minimum Investment | $10 |
| Maximum Investment | No limit |
| Multiple Investments | Yes, users can have multiple concurrent investments |
| Tier Classification | Based on USD equivalent |
| Investment Tracking | Each investment tracked independently with its own tier, reward rate, and duration |
| Principal Return | No principal returned when investment contract ends |
| Partial Withdrawal | Not allowed - invested amounts cannot be withdrawn mid-cycle |

**Note:** Each investment operates independently. There is no upgrade/downgrade of tier based on total investment amount. The percentage and duration follow per investment and are not lump sum.

---

## Referral Commission Structure

Commissions are calculated based on referrals' daily earnings (not investment amount) and are paid up to 3 levels in the referral chain.

| Level | Commission Rate | Description |
|-------|----------------|-------------|
| Level 1 | 50% | Direct referral (immediate downline) |
| Level 2 | 30% | Second-level referral |
| Level 3 | 20% | Third-level referral |
| Level 4+ | 0% | Beyond 3-level limit |

### Commission Calculation Rules

| Rule | Value |
|------|-------|
| Commission Basis | Daily reward amount earned by downline (not investment amount) |
| Commission Levels | Up to 3 levels |
| Commission Compounding | No - each level receives a percentage of the original daily reward amount |
| Commission Timing | Calculated immediately after reward calculation (same day) |
| Commission Crediting | Immediately (no 24-hour hold period) |
| Referral Tracking | All referral levels tracked, but commission calculation only up to 3 levels |

### Commission Calculation Example

**Scenario:**
- User A recruits User B
- User B recruits User C
- User C recruits User D
- User D recruits User E

**When User E earns a daily reward of $100:**
- User D (Level 1 from E) receives: 50% × $100 = **$50**
- User C (Level 2 from E) receives: 30% × $100 = **$30**
- User B (Level 3 from E) receives: 20% × $100 = **$20**
- User A receives: **$0** (Level 4, beyond the 3-level limit)

**Key Points:**
- Commissions do NOT compound - Level 2 gets 30% of the downline's daily reward, not 30% of Level 1's commission
- Each daily reward triggers a separate commission calculation up the chain (up to 3 levels)
- Commissions stop after the last day's reward is distributed when an investment contract expires

---

## Deposit Rules

Deposit rules govern how users can add credits to their account.

| Rule | Value |
|------|-------|
| Minimum Deposit | $5 |
| Maximum Deposit | No limit |
| Forfeiture | Deposits less than $5 will be forfeited (user sees transaction with status "forfeited") |
| Supported Cryptocurrencies | USDT on Tron, USDT on BNB |
| Processing | Payment gateway callback on on-chain deposit |
| Address Generation | System requests unique deposit address before showing to user |

### Deposit Transaction Lifecycle

| Status | Description |
|--------|-------------|
| `processing` | Payment gateway callback received on on-chain deposit |
| `completed` | When number of confirmations exceeds certain threshold for specific blockchain |
| `forfeited` | When deposit amount is less than minimum ($5) |

---

## Withdrawal Rules

Withdrawal rules govern how users can withdraw credits from their account.

| Rule | Value |
|------|-------|
| Minimum Withdrawal | $10 |
| Maximum Withdrawal | No limit |
| Processing Time | Within 5 business days |
| Supported Cryptocurrencies | USDT on Tron, USDT on BNB |

### Withdrawal Fees

| Blockchain | Fixed Fee | Percentage Fee |
|------------|-----------|----------------|
| Tron | $3 | 1% of withdrawal amount |
| Other Blockchains (BNB, etc.) | $2 | 1% of withdrawal amount |

**Total Fee Calculation:**
- Tron: `(withdrawal_amount × 1%) + $3`
- Other Blockchains: `(withdrawal_amount × 1%) + $2`

### Withdrawal Transaction Lifecycle

| Status | Description |
|--------|-------------|
| `pending` | Initial user request |
| `processing` | Only applies when withdrawal is sent for automated processing via payment gateway API. For manual processing (amount larger than threshold, admin configurable), status changes directly to `completed` when admin manually processes it |
| `completed` | Withdrawal successfully processed |
| `cancelled` | User or admin request to cancel withdrawal. System automatically refunds the withdrawal amount (including fees) back to user's wallet upon cancellation |

---

## Financial Precision

| Rule | Value |
|------|-------|
| Decimal Precision | 8 decimals for all financial amounts (balances, investments, rewards, commissions, deposits, withdrawals) |
| Rounding | Round to nearest (standard rounding) |
| Rationale | 8 decimals handles very small amounts and is crypto-friendly (matches most cryptocurrency precision standards) |

---

## Additional Business Rules

### Daily Reward Calculation

| Rule | Value |
|------|-------|
| First Reward Calculation | Starts at 00:00 UTC+8 on the day after investment |
| Reward Hold Period | 24 hours before being credited |
| Calculation Timing | Timezone: UTC+8 hours |
| Weekends/Holidays | Rewards are calculated on weekends and holidays |
| Multiple Investments | Each investment's reward is calculated independently based on its tier |

### Investment Contract Expiration

| Rule | Value |
|------|-------|
| Last Day Reward | Issued and distributed when contract ends |
| Commission on Last Day | Calculated immediately after the last day's reward is distributed |
| Principal Return | No principal returned when investment contract ends |

---

## Summary Tables

### Quick Reference: Investment Tiers

| Tier | Amount | Daily % | Days |
|------|--------|---------|------|
| 1 | ≤ $100 | 1.0% | 120 |
| 2 | ≤ $500 | 1.5% | 130 |
| 3 | ≤ $1,000 | 2.0% | 140 |
| 4 | ≤ $2,000 | 2.5% | 150 |
| 5 | ≤ $5,000 | 3.0% | 160 |
| 6 | > $5,000 | 3.5% | 180 |

### Quick Reference: Commission Rates

| Level | Rate |
|------|------|
| Level 1 | 50% |
| Level 2 | 30% |
| Level 3 | 20% |

### Quick Reference: Deposit/Withdrawal Limits

| Type | Minimum | Maximum | Forfeiture |
|------|---------|---------|------------|
| Deposit | $5 | No limit | < $5 forfeited |
| Withdrawal | $10 | No limit | N/A |

### Quick Reference: Withdrawal Fees

| Blockchain | Fixed Fee | Percentage |
|------------|-----------|------------|
| Tron | $3 | 1% |
| BNB (Other) | $2 | 1% |

---

## Notes for Business Owners

1. **Investment Independence:** Each investment is tracked independently. A user can have multiple investments at different tiers simultaneously.

2. **Commission Structure:** Commissions are based on daily rewards, not investment amounts. This means larger investments generate larger daily rewards, which in turn generate larger commissions for uplines.

3. **Referral Tracking:** While all referral levels are tracked in the system, commissions are only paid up to 3 levels. This limits the depth of commission payouts while maintaining full referral relationship tracking.

4. **Deposit Forfeiture:** Deposits under $5 are forfeited to prevent dust attacks and maintain transaction efficiency. Users will see these transactions marked as "forfeited" in their transaction history.

5. **Withdrawal Fees:** The fee structure includes both a percentage and a fixed fee. This ensures the system covers transaction costs while remaining competitive.

6. **Financial Precision:** All amounts use 8 decimal precision to handle very small amounts and maintain compatibility with cryptocurrency standards.

7. **Contract Duration:** Higher tiers have longer contract durations, providing more stability and longer-term engagement for larger investors.