feat: Implement Magic Wallet functionality

- Added ClubMembershipCycle entity and DbSet to IApplicationDbContext.
- Updated VAT rate from 9% to 10% in VatCalculator and related areas.
- Introduced Magic Wallet settings in SystemConstants.
- Enhanced UserWallet entity to support Magic Wallet features.
- Updated TransactionType enum to include Magic Wallet transactions.
- Configured UserWallet to handle Magic Wallet properties in ApplicationDbContext.
- Implemented OrmCommissionCalculationStrategy to exclude Magic Wallet users from commission calculations.
- Added Protobuf definitions for Magic Wallet methods and responses.
- Created PaymentCallbackController endpoint for handling Magic Wallet charge callbacks.
- Updated UserOrderService to manage Magic Wallet state transitions.
- Developed UserWalletService to support Magic Wallet operations.
- Created ChargeMagicWalletCommand and its handler for initiating Magic Wallet charges.
- Implemented VerifyMagicWalletChargeCommand and handler for payment verification.
- Added validation for ChargeMagicWalletCommand.
- Established ClubMembershipCycle configuration for EF Core.
- Introduced WalletMode enum to differentiate between Normal and Magic modes.

src/CMSMicroservice.Application/WalletCQ/Commands/ChargeMagicWallet/ChargeMagicWalletCommand.cs

@@ -0,0 +1,21 @@
+using CMSMicroservice.Application.Common.Interfaces;
+using MediatR;
+
+namespace CMSMicroservice.Application.WalletCQ.Commands.ChargeMagicWallet;
+
+/// <summary>
+/// شروع شارژ کیف‌پول جادویی از طریق درگاه پرداخت
+/// مبلغ واریزی × 2.5 به Balance اعتبار داده می‌شود
+/// </summary>
+public class ChargeMagicWalletCommand : IRequest<PaymentInitiateResult>
+{
+    /// <summary>
+    /// شناسه کاربر
+    /// </summary>
+    public long UserId { get; set; }
+
+    /// <summary>
+    /// مبلغ واریزی واقعی (ریال) — اعتبار = مبلغ × 2.5
+    /// </summary>
+    public long Amount { get; set; }
+}

src/CMSMicroservice.Application/WalletCQ/Commands/ChargeMagicWallet/ChargeMagicWalletCommandHandler.cs

@@ -0,0 +1,174 @@
+using CMSMicroservice.Application.Common.Exceptions;
+using CMSMicroservice.Application.Common.Interfaces;
+using CMSMicroservice.Domain.Common;
+using CMSMicroservice.Domain.Entities;
+using CMSMicroservice.Domain.Entities.Payment;
+using CMSMicroservice.Domain.Enums;
+using MediatR;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Logging;
+
+namespace CMSMicroservice.Application.WalletCQ.Commands.ChargeMagicWallet;
+
+public class ChargeMagicWalletCommandHandler
+    : IRequestHandler<ChargeMagicWalletCommand, PaymentInitiateResult>
+{
+    private readonly IApplicationDbContext _context;
+    private readonly IPaymentGatewayService _paymentGateway;
+    private readonly IConfiguration _configuration;
+    private readonly ILogger<ChargeMagicWalletCommandHandler> _logger;
+
+    public ChargeMagicWalletCommandHandler(
+        IApplicationDbContext context,
+        IPaymentGatewayService paymentGateway,
+        IConfiguration configuration,
+        ILogger<ChargeMagicWalletCommandHandler> logger)
+    {
+        _context = context;
+        _paymentGateway = paymentGateway;
+        _configuration = configuration;
+        _logger = logger;
+    }
+
+    public async Task<PaymentInitiateResult> Handle(
+        ChargeMagicWalletCommand request,
+        CancellationToken cancellationToken)
+    {
+        try
+        {
+            _logger.LogInformation(
+                "Initiating magic wallet charge for UserId: {UserId}, Amount: {Amount}",
+                request.UserId,
+                request.Amount
+            );
+
+            // 1. بررسی وجود کاربر
+            var user = await _context.Users
+                .FirstOrDefaultAsync(u => u.Id == request.UserId, cancellationToken);
+
+            if (user == null)
+            {
+                _logger.LogWarning("User not found: {UserId}", request.UserId);
+                throw new NotFoundException(nameof(User), request.UserId);
+            }
+
+            // 2. بررسی وجود کیف‌پول
+            var wallet = await _context.UserWallets
+                .FirstOrDefaultAsync(w => w.UserId == request.UserId, cancellationToken);
+
+            if (wallet == null)
+            {
+                _logger.LogError("Wallet not found for UserId: {UserId}", request.UserId);
+                throw new NotFoundException("کیف پول کاربر یافت نشد");
+            }
+
+            // 3. بررسی حالت جادویی
+            if (wallet.WalletMode != WalletMode.Magic)
+            {
+                _logger.LogWarning(
+                    "User {UserId} wallet is not in Magic mode (current: {Mode})",
+                    request.UserId,
+                    wallet.WalletMode
+                );
+                throw new BadRequestException(
+                    "شارژ جادویی فقط در حالت کیف‌پول جادویی امکان‌پذیر است"
+                );
+            }
+
+            // 4. بررسی سقف واریزی (per-cycle)
+            var remainingDeposit = SystemConstants.MagicWalletMaxDeposit - wallet.MagicTotalDeposited;
+
+            if (remainingDeposit <= 0)
+            {
+                _logger.LogWarning(
+                    "User {UserId} has reached magic deposit cap. TotalDeposited: {TotalDeposited}",
+                    request.UserId,
+                    wallet.MagicTotalDeposited
+                );
+                throw new BadRequestException(
+                    "سقف شارژ جادویی در این دور پر شده است"
+                );
+            }
+
+            if (request.Amount > remainingDeposit)
+            {
+                _logger.LogWarning(
+                    "User {UserId} amount {Amount} exceeds remaining deposit cap {Remaining}",
+                    request.UserId,
+                    request.Amount,
+                    remainingDeposit
+                );
+                throw new BadRequestException(
+                    $"مبلغ واریزی بیش از سقف باقیمانده است. حداکثر مبلغ قابل واریز: {remainingDeposit:N0} ریال"
+                );
+            }
+
+            // 5. ایجاد درخواست پرداخت
+            var cmsBaseUrl = _configuration["CmsBaseUrl"] ?? "https://localhost:32846";
+            var callbackUrl = $"{cmsBaseUrl}/api/wallet/verify-magic-charge";
+
+            var paymentRequest = new PaymentRequest
+            {
+                Amount = request.Amount,
+                UserId = user.Id,
+                Mobile = user.Mobile ?? "",
+                CallbackUrl = callbackUrl,
+                Description = $"شارژ کیف‌پول جادویی - کاربر {user.Id}"
+            };
+
+            var paymentResult = await _paymentGateway.InitiatePaymentAsync(paymentRequest);
+
+            if (!paymentResult.IsSuccess)
+            {
+                _logger.LogError(
+                    "Payment gateway failed for magic charge UserId {UserId}: {ErrorMessage}",
+                    user.Id,
+                    paymentResult.ErrorMessage
+                );
+
+                throw new Exception($"خطا در ارتباط با درگاه پرداخت: {paymentResult.ErrorMessage}");
+            }
+
+            // 6. ثبت PaymentTransaction
+            var paymentTx = new PaymentTransaction
+            {
+                GatewayProvider = _configuration["PaymentProvider"] ?? "zarinpal",
+                MerchantId = _configuration["ZarinPal:MerchantId"] ?? "",
+                Amount = request.Amount,
+                CallbackUrl = callbackUrl,
+                Description = $"شارژ کیف‌پول جادویی - کاربر {user.Id}",
+                Mobile = user.Mobile,
+                UserId = user.Id,
+                RequestStatusCode = 100,
+                RequestStatusMessage = "Success",
+                Authority = paymentResult.RefId,
+                PaymentStatus = false
+            };
+
+            _context.PaymentTransactions.Add(paymentTx);
+            await _context.SaveChangesAsync(cancellationToken);
+
+            _logger.LogInformation(
+                "Magic wallet charge initiated. UserId: {UserId}, Amount: {Amount}, " +
+                "RemainingCap: {Remaining}, RefId: {RefId}, PaymentTxId: {PaymentTxId}",
+                user.Id,
+                request.Amount,
+                remainingDeposit - request.Amount,
+                paymentResult.RefId,
+                paymentTx.Id
+            );
+
+            return paymentResult;
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(
+                ex,
+                "Error in ChargeMagicWalletCommand for UserId: {UserId}",
+                request.UserId
+            );
+            throw;
+        }
+    }
+}

src/CMSMicroservice.Application/WalletCQ/Commands/ChargeMagicWallet/ChargeMagicWalletCommandValidator.cs

@@ -0,0 +1,19 @@
+using FluentValidation;
+
+namespace CMSMicroservice.Application.WalletCQ.Commands.ChargeMagicWallet;
+
+public class ChargeMagicWalletCommandValidator : AbstractValidator<ChargeMagicWalletCommand>
+{
+    public ChargeMagicWalletCommandValidator()
+    {
+        RuleFor(x => x.UserId)
+            .GreaterThan(0)
+            .WithMessage("شناسه کاربر باید بزرگتر از صفر باشد");
+
+        RuleFor(x => x.Amount)
+            .GreaterThanOrEqualTo(100_000)
+            .WithMessage("حداقل مبلغ شارژ جادویی ۱۰,۰۰۰ تومان است")
+            .LessThanOrEqualTo(1_000_000_000)
+            .WithMessage("حداکثر مبلغ شارژ جادویی ۱۰۰,۰۰۰,۰۰۰ تومان است");
+    }
+}