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

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

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

---

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

مفهوم	توضیح
عضویت باشگاه	خرید پکیج طلایی (۵۶M) → فعالسازی (۲۵.۲M) → عضو فعال باشگاه
درخت باینری	هر کاربر حداکثر ۲ فرزند مستقیم (چپ/راست) — بدون محدودیت عمق
کمیسیون هفتگی	محاسبه بر اساس تعادل چپ/راست — یکشنبه ۰۰:۰۵ (Hangfire cron)
۳ کیف پول	Balance (نقدی) + NetworkBalance (طلایی/کمیسیون) + DiscountBalance (تخفیفی)

---

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

              Root
             /    \
          Left    Right
         /   \    /   \
       L1    L2  R1    R2
      / \   / \ / \   / \
     ...  ...  ...  ...  ...     ← بدون محدودیت عمق

قوانین:

• هر نود حداکثر ۲ فرزند (Binary) — MaxDirectChildrenPerLeg = 1
• جایگذاری: LegPosition ∈ {Left=0, Right=1} (enum NetworkLeg)
• مدل شبکه مستقیم روی entity User — فیلدهای NetworkParentId, LegPosition, NetworkChildren
• محاسبه کمیسیون تا عمق ۱۵ سطح (CommissionMaxNetworkLevel = 15) — اما درخت بدون محدودیت رشد می‌کند

---

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

خرید پکیج طلایی (56M تومان)
    │
    ▼
نمایش مودال قرارداد (غیرقابل‌بسته‌شدن)
    │
    ▼
مشاهده متن قرارداد ← ReadContract RPC
    │
    ▼
درخواست OTP ← RequestContractOtp (Kavenegar SMS)
    │
    ▼
وارد کردن کد ← VerifyContractOtp
    │
    ▼
امضای قرارداد ← AcceptContract
    │
    ├─→ شارژ ۲ کیف پول: Balance += 56M, DiscountBalance += 112M (2×)
    │   (NetworkBalance شارژ نمی‌شود — فقط برای کمیسیون)
    ├─→ کسر هزینه فعالسازی (25.2M از Balance)
    ├─→ واریز 25.2M به Pool هفتگی (ClubActivationFee)
    ├─→ قرارگیری در درخت باینری
    └─→ رفرش JWT Token (claims جدید)

⚠️ در خرید با وام دایا:
    ├─→ Balance += 56M
    └─→ DiscountBalance += 112M (دو برابر — DayaLoanAmount × 2)

---

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

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

مرحله ۱: جمع فروش هر پا
  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)

ثابت (SystemConstants)	مقدار	توضیح
ClubActivationFee	25,200,000	هزینه فعالسازی (ریال)
ClubMembershipGiftValue	25,200,000	واریز به Pool
BasePackageAmount	56,000,000	قیمت پکیج طلایی (ریال)
DayaLoanAmount	56,000,000	مبلغ وام دایا (ریال)
CommissionMaxWeeklyBalancesPerLeg	300	سقف هفتگی هر پا
CommissionMaxNetworkLevel	15	عمق محاسبه کمیسیون (نه محدودیت درخت)
MaxDirectChildrenPerLeg	1	حداکثر فرزند مستقیم هر پا
MinimumWithdrawAmount	1,000,000	حداقل مبلغ برداشت (ریال)
ShopVAT	0.1 (10%)	مالیات ارزش افزوده
CommissionCalculationMethod	"SP"	روش محاسبه = Stored Procedure

---

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

سناریو	فلو	وضعیت
وام دایا	درخواست وام → تأیید → Balance=56M + Discount=112M (مجموع ۱۶۸M)	✅ پیاده‌شده
درگاه مستقیم	IPG → callback → Balance=56M + Discount=112M (مجموع ۱۶۸M)	✅ پیاده‌شده
پرداخت دستی	کارت‌به‌کارت → آپلود رسید → تأیید ادمین → شارژ	⚠️ طراحی‌شده

---

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

Hangfire Worker (هر ۲۰ دقیقه — cron: */20 * * * *)
    │
    ▼
بررسی درخواست‌های pending
    │
    ▼
ارسال به API دایا (Mock/Real switchable)
    │
    ▼
دریافت نتیجه → شارژ ۲ کیف‌پول
    │
    ├─→ Balance += 56M  (DayaLoanAmount)
    └─→ DiscountBalance += 112M  (DayaLoanAmount × 2 — دو برابر)
        مجموع: 168M

Hangfire retry: [AutomaticRetry(Attempts = 3)]

---

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

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