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/features/billing/PaymentRequestPanel.tsx

@@ -103,8 +103,12 @@ export function PaymentRequestPanel({ status }: { status: BillingStatusDto }) {
       </CardHeader>
       <CardContent className="flex flex-col gap-4">
         <p className="text-sm">
-          {t(`billing.periods.${request.period}`)} — <span className="font-medium">{request.amountSnapshot} ₽</span>
+          {request.kind === 'RoleChangeTopUp' ? t('billing.roleChangeTopUp') : t(`billing.periods.${request.period}`)} —{' '}
+          <span className="font-medium">{request.amountSnapshot} ₽</span>
         </p>
+        {request.kind === 'RoleChangeTopUp' && (
+          <p className="text-xs text-muted-foreground">{t('billing.roleChangeTopUpHint')}</p>
+        )}
 
         {!isAwaitingConfirmation && (
           <div className="flex flex-col gap-1.5">

frontend/src/routes/admin/billing.tsx

@@ -162,7 +162,9 @@ function RequestsSection() {
               {data.items.map((request) => (
                 <tr key={request.id} className="border-b border-border">
                   <td className="py-2">{request.userName}</td>
-                  <td className="py-2">{t(`billing.periods.${request.period}`)}</td>
+                  <td className="py-2">
+                    {request.kind === 'RoleChangeTopUp' ? t('billing.roleChangeTopUp') : t(`billing.periods.${request.period}`)}
+                  </td>
                   <td className="py-2">{request.amountSnapshot} ₽</td>
                   <td className="py-2">
                     <Badge variant={request.status === 'AwaitingConfirmation' ? 'warning' : 'outline'}>

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: {