# Commission Frequency Implementation

## Overview

This implementation enables the use of biannual and annual commission rates based on subscription plan duration. Previously, all commission calculations used monthly rates regardless of the subscription plan. Now, the system automatically selects the appropriate commission frequency based on the subscription plan's duration.

## Key Features

### 1. Automatic Frequency Detection
- **1-month plans**: Use monthly commission rates (higher rates)
- **6-month plans**: Use biannual commission rates (lower rates)  
- **12-month plans**: Use annual commission rates (lower rates)
- **Other durations**: Default to monthly rates

### 2. Commission Rate Structure
```
Monthly Rates:
- SFMO: 55%
- FMO: 50%
- SVG: 45%
- MGA: 40%
- AGENT: 30%
- ASSOCIATE: 20%

Biannual/Annual Rates:
- SFMO: 27.5%
- FMO: 25%
- SVG: 23%
- MGA: 20%
- AGENT: 15%
- ASSOCIATE: 14%
```

## Implementation Details

### 1. SubscriptionPlan Model Enhancement
**File**: `app/Models/SubscriptionPlan.php`

Added methods:
- `getCommissionFrequency()`: Maps duration_months to commission frequency
- `isBiannualCommission()`: Checks if plan uses biannual rates
- `isAnnualCommission()`: Checks if plan uses annual rates

### 2. Agent Model Enhancement
**File**: `app/Models/Agent.php`

Added methods:
- `calculateCommissionForSubscription()`: Calculates commission based on subscription plan
- `calculateUplineCommissionForSubscription()`: Calculates upline commission based on subscription plan

### 3. Commission Service Updates
**File**: `app/Services/CommissionService.php`

The service already supported frequency-based calculations and was enhanced to work seamlessly with the new subscription-based approach.

### 4. Agent Referral Service Updates
**File**: `app/Services/AgentReferralService.php`

Updated to:
- Use subscription-based commission calculations
- Store commission frequency in commission records
- Automatically determine frequency from subscription plan

### 5. Commission Calculation Action Updates
**File**: `app/Actions/Agents/CalculateCommissionAction.php`

Updated to:
- Use subscription-based commission calculations
- Store commission frequency in commission records

### 6. Database Schema Enhancement
**Migration**: `database/migrations/2025_07_16_125140_add_commission_frequency_to_agent_commissions_table.php`

Added `commission_frequency` field to `agent_commissions` table:
- Type: ENUM('monthly', 'biannual', 'annual')
- Default: 'monthly'
- Indexed for performance

**Model**: `app/Models/AgentCommission.php`
- Added `commission_frequency` to fillable fields

## Usage Examples

### Example 1: Monthly Subscription
```php
$monthlyPlan = SubscriptionPlan::create(['duration_months' => 1, 'price' => 59.99]);
$subscription = Subscription::create(['plan_id' => $monthlyPlan->id, ...]);

// Commission calculation will use monthly rates (30% for AGENT)
$commission = $agent->calculateCommissionForSubscription(100.00, $subscription);
// Result: $30.00
```

### Example 2: Annual Subscription
```php
$annualPlan = SubscriptionPlan::create(['duration_months' => 12, 'price' => 299.99]);
$subscription = Subscription::create(['plan_id' => $annualPlan->id, ...]);

// Commission calculation will use annual rates (15% for AGENT)
$commission = $agent->calculateCommissionForSubscription(100.00, $subscription);
// Result: $15.00
```

### Example 3: Commission Record Tracking
```php
// When a commission is created, it now includes frequency information
$commission = AgentCommission::create([
    'agent_id' => $agent->id,
    'transaction_id' => $transaction->id,
    'subscription_id' => $subscription->id,
    'commission_amount' => 15.00,
    'commission_frequency' => 'annual', // Automatically determined
    // ... other fields
]);
```

## Benefits

1. **Accurate Commission Calculations**: Commissions now reflect the actual subscription plan duration
2. **Lower Rates for Longer Commitments**: Annual and biannual plans have lower commission rates, encouraging longer-term subscriptions
3. **Automatic Detection**: No manual configuration needed - frequency is automatically determined from subscription plan
4. **Audit Trail**: Commission records now track which frequency was used for each calculation
5. **Backward Compatibility**: Existing monthly calculations continue to work unchanged

## Testing

The implementation includes comprehensive testing that verifies:
- Subscription plan frequency mapping
- Commission rate calculations for all frequencies
- Upline commission calculations
- Commission record creation with frequency tracking

## Migration Instructions

1. Run the migration to add the commission_frequency field:
   ```bash
   php artisan migrate
   ```

2. The system will automatically start using the new frequency-based calculations for new transactions.

3. Existing commission records will have `commission_frequency` set to 'monthly' by default.

## Configuration

Commission rates are configured in `config/commission.php`:
- `commission.rates.monthly`: Monthly commission rates
- `commission.rates.biannual`: Biannual commission rates  
- `commission.rates.annual`: Annual commission rates

No additional configuration is required - the system automatically uses the appropriate rates based on subscription plan duration.