Reestruturar o README: assimetria entre gateways, markdown quebrado e lacunas que causam erro de cobrança

[mariolucasdev]

O README cresceu por acréscimo: cada gateway novo virou uma seção no fim, e a estrutura não acompanhou. Com cinco gateways e 528 linhas, ficaram problemas concretos.

Problemas

• O Asaas não tem seção própria. As subseções "Cobranças" e "Assinaturas" dentro de "Como usar o PHPay?" são dele, mas sem rótulo — enquanto Mercado Pago e PagBank ganharam seções de primeiro nível. O leitor não sabe a qual gateway o primeiro exemplo se refere.
• Sem sumário, em um documento de 500+ linhas.
• Markdown quebrado no roadmap: a lista aninhada não renderiza indentada, então tudo vira lista plana e os gateways se misturam.
• Requisitos escondidos dentro de outra seção.
• Conteúdo transversal repetido por gateway, em vez de explicado uma vez.
• Sem seção de segurança, apesar de ser uma biblioteca de pagamentos.

O que falta documentar, e faz falta de verdade

• Unidade monetária por gateway. Asaas e Mercado Pago usam reais decimais; PagBank, Pagar.me e Efí usam centavos inteiros. Errar isso não quebra a integração — ela cobra o valor errado, que é pior.
• Como cada gateway separa ambiente. Três usam $sandbox para trocar a URL; dois decidem pelo prefixo da credencial.
• Por que a matriz de capacidades tem tantos espaços vazios. Sem explicação, parece que o gateway não aceita Pix — quando na verdade SupportsPixKeys significa gerenciar chaves, coisa de PSP.

Bug encontrado

examples/efi/charges.php passa 'value' => 100.00. O Efí usa centavos, então o exemplo cobraria R$ 1,00, não R$ 100,00.