Refactor payment request handling to support role change top-ups

- Updated the `PaymentRequest` model to include a new `Kind` property, distinguishing between `Subscription` and `RoleChangeTopUp` requests.
- Modified the `TelegramNotifier` to accommodate the new request type, ensuring accurate notifications for role change top-ups.
- Enhanced the `ConfirmPaymentRequestCommandHandler` to handle role change top-ups without extending the billing period, reflecting the new payment logic.
- Updated various application components and tests to support the new payment request structure and ensure proper functionality.
- Revised API documentation to clarify the behavior of role change top-ups and their impact on billing.

backend/src/PnvPanel.Application/Admin/Billing/ConfirmPaymentRequestCommandHandler.cs

@@ -50,9 +50,37 @@ public sealed class ConfirmPaymentRequestCommandHandler(
         if (profile is null)
             return Result.Failure(AuthErrors.Unauthorized);
 
+        // RoleChangeTopUp — доплата разницы в цене при апгрейде роли, не покупка времени: подтверждение
+        // не трогает BillingPaidUntil и не возвращает Expired-конфиги (это делает обычная Subscription-
+        // оплата/продление). Period не задан для этого Kind — ToMonths() здесь неприменим.
+        if (request.Kind == PaymentRequestKind.RoleChangeTopUp)
+        {
+            request.Confirm(adminId);
+
+            dbContext.AuditLogs.Add(
+                AuditLog.Create(
+                    adminId,
+                    "PaymentConfirmed",
+                    "PaymentRequest",
+                    request.Id.ToString(),
+                    metadata: null,
+                    AuditSource.Web
+                )
+            );
+
+            await telegramNotifier.NotifyUserAsync(
+                request.UserId,
+                "✅ Доплата за смену роли подтверждена.",
+                null,
+                cancellationToken
+            );
+
+            return Result.Success();
+        }
+
         var now = DateTimeOffset.UtcNow;
         var baseline = profile.BillingPaidUntil is { } paidUntil && paidUntil > now ? paidUntil : now;
-        var newPaidUntil = baseline.AddMonths(request.Period.ToMonths());
+        var newPaidUntil = baseline.AddMonths(request.Period!.Value.ToMonths());
 
         var extendResult = await identityService.ExtendBillingPaidUntilAsync(
             request.UserId,