# 🏆 سیستم باشگاه، کمیسیون و درخت شبکه‌ای

> **منابع ادغام‌شده:** `club-commission-system-complete.md`, `balance-calculation-rules.md`, `club-membership-contract-system.md`  
> **آخرین بروزرسانی:** اسفند ۱۴۰۴

---

## ۱. مفاهیم کلیدی

| مفهوم | توضیح |
|-------|--------|
| **عضویت باشگاه** | خرید پکیج طلایی (۵۶M) → فعالسازی (۲۵M) → عضو فعال باشگاه |
| **درخت باینری** | هر کاربر حداکثر ۲ فرزند مستقیم (چپ/راست) — حداکثر ۱۵ سطح |
| **کمیسیون هفتگی** | محاسبه بر اساس تعادل چپ/راست — هفته شمسی شنبه‌تا‌جمعه |
| **۳ کیف پول** | `Balance` (نقدی) + `NetworkBalance` (شبکه‌ای) + `DiscountBalance` (تخفیفی) |

---

## ۲. ساختار درخت باینری

```
              Root
             /    \
          Left    Right
         /   \    /   \
       L1    L2  R1    R2
      / \   / \ / \   / \
     ...  ...  ...  ...  ...     ← حداکثر ۱۵ سطح
```

**قوانین:**
- هر نود حداکثر ۲ فرزند (Binary)
- جایگذاری: `LegPosition` ∈ {Left, Right}
- عضو جدید → در اولین جای خالی از چپ‌ترین مسیر قرار می‌گیرد
- `SP_GetNetworkTree` — Stored Procedure بازگشتی

---

## ۳. فلوی عضویت و فعالسازی

```
خرید پکیج طلایی (56M تومان)
    │
    ▼
نمایش مودال قرارداد (غیرقابل‌بسته‌شدن)
    │
    ▼
مشاهده متن قرارداد ← ReadContract RPC
    │
    ▼
درخواست OTP ← RequestContractOtp (Kavenegar SMS)
    │
    ▼
وارد کردن کد ← VerifyContractOtp
    │
    ▼
امضای قرارداد ← AcceptContract
    │
    ├─→ شارژ ۳ کیف پول (Balance=56M, Network=56M, Discount=56M)
    ├─→ کسر هزینه فعالسازی (25M از Balance)
    ├─→ واریز 25.2M به Pool هفتگی
    ├─→ قرارگیری در درخت باینری
    └─→ رفرش JWT Token (claims جدید)
```

---

## ۴. الگوریتم محاسبه کمیسیون هفتگی

### ۴.۱ فرمول ۴ مرحله‌ای

```
مرحله ۱: جمع فروش هر پا
  SumLeft  = Σ(فروش‌های پای چپ در هفته جاری + CanOverLeft)
  SumRight = Σ(فروش‌های پای راست در هفته جاری + CanOverRight)

مرحله ۲: محاسبه تعادل
  WeeklyBalance = MIN(SumLeft, SumRight)

مرحله ۳: محاسبه باقیمانده (Carryover)
  CanOverLeft  = SumLeft  - WeeklyBalance
  CanOverRight = SumRight - WeeklyBalance

مرحله ۴: سقف هفتگی
  IF WeeklyBalance > 300  →  WeeklyBalance = 300
  IF CanOverLeft > 300    →  Flush (CanOverLeft = 0)
  IF CanOverRight > 300   →  Flush (CanOverRight = 0)
```

### ۴.۲ مثال عددی (درخت ۵ سطحی)

```
هفته ۱:  چپ=120, راست=80  →  Balance=80, Over(L=40, R=0)
هفته ۲:  چپ=90+40=130, راست=150  →  Balance=130, Over(L=0, R=20)
هفته ۳:  چپ=200, راست=180+20=200  →  Balance=200, Over(L=0, R=0)
هفته ۴:  چپ=500, راست=100  →  Balance=100, Over(L=400→FLUSH=0, R=0)
```

### ۴.۳ Pool هفتگی و توزیع

```
منبع Pool: هر فعالسازی عضو → 25.2M واریز به Pool
توزیع: بر اساس WeeklyBalance هر عضو / مجموع WeeklyBalance‌ها
SP: sp_CalculateWeeklyBalances → sp_CalculateWeeklyCommissionPool
فرمت هفته: "YYYY-Www" (شمسی، شنبه‌پایه)
```

---

## ۵. تنظیمات سیستمی (SystemConstants)

| ثابت | مقدار | توضیح |
|------|-------|--------|
| `Club.ActivationFee` | 25,000,000 | هزینه فعالسازی (تومان) |
| `Club.GiftValue` | 25,200,000 | واریز به Pool |
| `GoldenPackageAmount` | 56,000,000 | قیمت پکیج طلایی |
| `DayaLoanAmount` | 56,000,000 | مبلغ وام دایا |
| `MaxWeeklyBalancesPerLeg` | 300 | سقف هفتگی هر پا |
| `MaxNetworkLevel` | 15 | حداکثر عمق درخت |
| `ClubJoiningPercentage` | 0.35 | درصد پیوستن |
| `ClubActivationThreshold` | 0.5 | آستانه فعالسازی |
| `MaxCalculationAttempts` | 3 | حداکثر تلاش محاسبه |

---

## ۶. ۳ سناریوی خرید پکیج طلایی

| سناریو | فلو | وضعیت |
|--------|------|--------|
| **وام دایا** | درخواست وام → تأیید خودکار → شارژ ۳ کیف‌پول (۱۶۸M) | ✅ پیاده‌شده |
| **درگاه مستقیم** | IPG (ZarinPal) → callback → شارژ | ✅ پیاده‌شده |
| **پرداخت دستی** | کارت‌به‌کارت → آپلود رسید → تأیید ادمین → شارژ | ⚠️ طراحی‌شده |

---

## ۷. یکپارچه‌سازی وام دایا

```
Hangfire Worker (هر ۱۵ دقیقه)
    │
    ▼
بررسی درخواست‌های pending
    │
    ▼
ارسال به API دایا (Mock/Real switchable)
    │
    ▼
دریافت نتیجه → شارژ ۳ کیف‌پول
    │
    ├─→ Balance = 56M
    ├─→ NetworkBalance = 56M
    └─→ DiscountBalance = 56M  (مجموع: 168M)

Polly Retry: 3 attempts, Exponential backoff
```

---

## ۸. Chatika AI — اولین فیچر باشگاه

| آیتم | جزئیات |
|------|---------|
| **نوع** | Hangfire recurring job |
| **فرکانس** | هر ۵ دقیقه |
| **Retry** | Polly — ۳ تلاش، backoff نمایی |
| **فعال‌سازی** | فقط برای اعضای فعال باشگاه |
| **وضعیت** | ✅ Production ready |