docs/business/BUSINESS-01-CLUB-COMMISSION.md

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

منابع ادغام‌شده: 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