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 (تخفیفی)

---

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

graph TD
    ROOT["Root"] --- L["Left"]
    ROOT --- R["Right"]
    L --- L1["L1"] & L2["L2"]
    R --- R1["R1"] & R2["R2"]
    L1 --- L1a["..."] & L1b["..."]
    L2 --- L2a["..."] & L2b["..."]
    R1 --- R1a["..."] & R1b["..."]
    R2 --- R2a["..."] & R2b["..."]

← بدون محدودیت عمق

قوانین:

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

---

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

flowchart TD
    A["خرید پکیج طلایی — 56M"] --> B["نمایش مودال قرارداد\nغیرقابل‌بسته‌شدن"]
    B --> C["مشاهده متن قرارداد\nReadContract RPC"]
    C --> D["درخواست OTP\nRequestContractOtp — Kavenegar"]
    D --> E["وارد کردن کد\nVerifyContractOtp"]
    E --> F["امضای قرارداد\nAcceptContract"]

    F --> G["شارژ ۲ کیف‌پول\nBalance += 56M\nDiscountBalance += 112M"]
    F --> H["کسر فعالسازی\n−25.2M از Balance"]
    F --> I["واریز 25.2M\nبه Pool هفتگی"]
    F --> J["قرارگیری در\nدرخت باینری"]
    F --> K["رفرش JWT Token\nclaims جدید"]

⚠️ در خرید با وام دایا: Balance += 56M, DiscountBalance += 112M (DayaLoanAmount × 2)
NetworkBalance شارژ نمی‌شود — فقط برای کمیسیون

---

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

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

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

flowchart LR
    A["هر فعالسازی عضو\n25.2M واریز"] --> B["Pool هفتگی"]
    B --> C["sp_CalculateWeeklyBalances"]
    C --> D["sp_CalculateWeeklyCommissionPool"]
    D --> E["توزیع بر اساس\nUserBalance / TotalBalance"]

فرمت هفته: 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)	✅ پیاده‌شده
پرداخت دستی	کارت‌به‌کارت → آپلود رسید → تأیید ادمین → شارژ	⚠️ طراحی‌شده

---

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

flowchart TD
    A["Hangfire Worker\nهر ۲۰ دقیقه — */20 * * * *"] --> B["بررسی درخواست‌های pending"]
    B --> C["ارسال به API دایا\nMock/Real switchable"]
    C --> D["دریافت نتیجه"]
    D --> E["Balance += 56M"]
    D --> F["DiscountBalance += 112M\nDayaLoanAmount × 2"]

مجموع شارژ: 168M — Hangfire retry: [AutomaticRetry(Attempts = 3)]

---

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

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