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.

frontend/src/shared/api/types.ts

@@ -202,10 +202,14 @@ export type PaymentRequestStatus =
   | 'Confirmed'
   | 'Rejected'
   | 'Cancelled'
+/** Subscription — оплата за период (period задан). RoleChangeTopUp — доплата разницы в цене при
+ * апгрейде роли с активным оплаченным периодом (period null, не продлевает paidUntil). */
+export type PaymentRequestKind = 'Subscription' | 'RoleChangeTopUp'
 
 export type PaymentRequestDto = {
   id: string
-  period: PaymentPeriod
+  kind: PaymentRequestKind
+  period: PaymentPeriod | null
   amountSnapshot: number
   status: PaymentRequestStatus
   createdAt: string
@@ -231,7 +235,8 @@ export type AdminPaymentRequestDto = {
   id: string
   userId: string
   userName: string
-  period: PaymentPeriod
+  kind: PaymentRequestKind
+  period: PaymentPeriod | null
   amountSnapshot: number
   status: PaymentRequestStatus
   createdAt: string

frontend/src/shared/lib/i18n.ts

@@ -142,6 +142,8 @@ const resources = {
         confirmCancel: 'Отменить заявку на оплату?',
         requestCancelled: 'Заявка отменена.',
         awaitingAdminHint: 'Администратор уведомлён и проверит оплату. Конфиги не отключатся, пока заявка не решена.',
+        roleChangeTopUp: 'Доплата за смену роли',
+        roleChangeTopUpHint: 'Новая роль дороже прежней — эта сумма покрывает разницу в цене за оставшуюся часть уже оплаченного периода, срок подписки при этом не меняется.',
       },
 
       instructions: {
@@ -680,6 +682,8 @@ const resources = {
         confirmCancel: 'Cancel this payment request?',
         requestCancelled: 'Request cancelled.',
         awaitingAdminHint: 'The administrator has been notified and will verify the payment. Configs stay active until the request is decided.',
+        roleChangeTopUp: 'Role change top-up',
+        roleChangeTopUpHint: "Your new role costs more than the old one — this amount covers the price difference for the remaining part of your already-paid period; your subscription end date doesn't change.",
       },
 
       instructions: {